IRIX Base Documentation 2001 May/SGI IRIX Base Documentation 2001 May.iso/usr/share/catman/p_man/cat3c/getutx.z/getutx

Text File | 2001-04-17 | 22.8 KB | 265 lines

ggggeeeettttuuuuttttxxxx((((3333CCCC))))                                                          ggggeeeettttuuuuttttxxxx((((3333CCCC))))



NNNNAAAAMMMMEEEE
     getutx: _gggg_eeee_tttt_uuuu_tttt_xxxx_eeee_nnnn_tttt_,,,, _gggg_eeee_tttt_uuuu_tttt_xxxx_iiii_dddd_,,,, _gggg_eeee_tttt_uuuu_tttt_xxxx_llll_iiii_nnnn_eeee_,,,, _pppp_uuuu_tttt_uuuu_tttt_xxxx_llll_iiii_nnnn_eeee_,,,, _ssss_eeee_tttt_uuuu_tttt_xxxx_eeee_nnnn_tttt_,,,,
     _eeee_nnnn_dddd_uuuu_tttt_xxxx_eeee_nnnn_tttt_,,,, _uuuu_tttt_mmmm_pppp_xxxx_nnnn_aaaa_mmmm_eeee_,,,, _gggg_eeee_tttt_uuuu_tttt_mmmm_pppp_,,,, _gggg_eeee_tttt_uuuu_tttt_mmmm_pppp_xxxx_,,,, _uuuu_pppp_dddd_wwww_tttt_mmmm_pppp_,,,, _uuuu_pppp_dddd_wwww_tttt_mmmm_pppp_xxxx - access _uuuu_tttt_mmmm_pppp_xxxx
     (extended _uuuu_tttt_mmmm_pppp) file entry

SSSSYYYYNNNNOOOOPPPPSSSSIIIISSSS
     _####_iiii_nnnn_cccc_llll_uuuu_dddd_eeee _<<<<_uuuu_tttt_mmmm_pppp_xxxx_...._hhhh_>>>>

     _ssss_tttt_rrrr_uuuu_cccc_tttt _uuuu_tttt_mmmm_pppp_xxxx _****_gggg_eeee_tttt_uuuu_tttt_xxxx_eeee_nnnn_tttt _((((_vvvv_oooo_iiii_dddd_))))_;;;;

     _ssss_tttt_rrrr_uuuu_cccc_tttt _uuuu_tttt_mmmm_pppp_xxxx _****_gggg_eeee_tttt_uuuu_tttt_xxxx_iiii_dddd _((((_cccc_oooo_nnnn_ssss_tttt _ssss_tttt_rrrr_uuuu_cccc_tttt _uuuu_tttt_mmmm_pppp_xxxx _****_iiii_dddd_))))_;;;;

     _ssss_tttt_rrrr_uuuu_cccc_tttt _uuuu_tttt_mmmm_pppp_xxxx _****_gggg_eeee_tttt_uuuu_tttt_xxxx_llll_iiii_nnnn_eeee _((((_cccc_oooo_nnnn_ssss_tttt _ssss_tttt_rrrr_uuuu_cccc_tttt _uuuu_tttt_mmmm_pppp_xxxx _****_llll_iiii_nnnn_eeee_))))_;;;;

     _ssss_tttt_rrrr_uuuu_cccc_tttt _uuuu_tttt_mmmm_pppp_xxxx _****_pppp_uuuu_tttt_uuuu_tttt_xxxx_llll_iiii_nnnn_eeee _((((_cccc_oooo_nnnn_ssss_tttt _ssss_tttt_rrrr_uuuu_cccc_tttt _uuuu_tttt_mmmm_pppp_xxxx _****_uuuu_tttt_mmmm_pppp_xxxx_))))_;;;;

     _vvvv_oooo_iiii_dddd _ssss_eeee_tttt_uuuu_tttt_xxxx_eeee_nnnn_tttt _((((_vvvv_oooo_iiii_dddd_))))_;;;;

     _vvvv_oooo_iiii_dddd _eeee_nnnn_dddd_uuuu_tttt_xxxx_eeee_nnnn_tttt _((((_vvvv_oooo_iiii_dddd_))))_;;;;

     _iiii_nnnn_tttt _uuuu_tttt_mmmm_pppp_xxxx_nnnn_aaaa_mmmm_eeee _((((_cccc_oooo_nnnn_ssss_tttt _cccc_hhhh_aaaa_rrrr _****_ffff_iiii_llll_eeee_))))_;;;;

     _vvvv_oooo_iiii_dddd _gggg_eeee_tttt_uuuu_tttt_mmmm_pppp _((((_ssss_tttt_rrrr_uuuu_cccc_tttt _uuuu_tttt_mmmm_pppp_xxxx _****_uuuu_tttt_mmmm_pppp_xxxx_,,,, _ssss_tttt_rrrr_uuuu_cccc_tttt _uuuu_tttt_mmmm_pppp _****_uuuu_tttt_mmmm_pppp_))))_;;;;

     _vvvv_oooo_iiii_dddd _gggg_eeee_tttt_uuuu_tttt_mmmm_pppp_xxxx _((((_ssss_tttt_rrrr_uuuu_cccc_tttt _uuuu_tttt_mmmm_pppp _****_uuuu_tttt_mmmm_pppp_,,,, _ssss_tttt_rrrr_uuuu_cccc_tttt _uuuu_tttt_mmmm_pppp_xxxx _****_uuuu_tttt_mmmm_pppp_xxxx_))))_;;;;

     _vvvv_oooo_iiii_dddd _uuuu_pppp_dddd_wwww_tttt_mmmm_pppp _((((_cccc_hhhh_aaaa_rrrr _****_wwww_ffff_iiii_llll_eeee_,,,, _ssss_tttt_rrrr_uuuu_cccc_tttt _uuuu_tttt_mmmm_pppp _****_uuuu_tttt_mmmm_pppp_))))_;;;;

     _vvvv_oooo_iiii_dddd _uuuu_pppp_dddd_wwww_tttt_mmmm_pppp_xxxx _((((_cccc_hhhh_aaaa_rrrr _****_wwww_ffff_iiii_llll_eeee_xxxx_,,,, _ssss_tttt_rrrr_uuuu_cccc_tttt _uuuu_tttt_mmmm_pppp_xxxx _****_uuuu_tttt_mmmm_pppp_xxxx_))))_;;;;

DDDDEEEESSSSCCCCRRRRIIIIPPPPTTTTIIIIOOOONNNN
     _gggg_eeee_tttt_uuuu_tttt_xxxx_eeee_nnnn_tttt, _gggg_eeee_tttt_uuuu_tttt_xxxx_iiii_dddd, and _gggg_eeee_tttt_uuuu_tttt_xxxx_llll_iiii_nnnn_eeee each return a pointer to a _uuuu_tttt_mmmm_pppp_xxxx
     structure:

          _ssss_tttt_rrrr_uuuu_cccc_tttt     _uuuu_tttt_mmmm_pppp_xxxx _{{{{
               _cccc_hhhh_aaaa_rrrr     _uuuu_tttt______uuuu_ssss_eeee_rrrr_[[[[_3333_2222_]]]]_;;;;   _////_**** _uuuu_ssss_eeee_rrrr _llll_oooo_gggg_iiii_nnnn _nnnn_aaaa_mmmm_eeee _****_////
               _cccc_hhhh_aaaa_rrrr     _uuuu_tttt______iiii_dddd_[[[[_4444_]]]]_;;;;      _////_**** _////_eeee_tttt_cccc_////_iiii_nnnn_iiii_tttt_tttt_aaaa_bbbb _iiii_dddd _((((_uuuu_ssss_uuuu_aaaa_llll_llll_yyyy _****_////
                                       _////_**** _llll_iiii_nnnn_eeee _####_)))) _****_////
               _cccc_hhhh_aaaa_rrrr     _uuuu_tttt______llll_iiii_nnnn_eeee_[[[[_3333_2222_]]]]_;;;;   _////_**** _dddd_eeee_vvvv_iiii_cccc_eeee _nnnn_aaaa_mmmm_eeee _((((_cccc_oooo_nnnn_ssss_oooo_llll_eeee_,,,, _llll_nnnn_xxxx_xxxx_)))) _****_////
               _pppp_iiii_dddd______tttt    _uuuu_tttt______pppp_iiii_dddd_;;;;        _////_**** _pppp_rrrr_oooo_cccc_eeee_ssss_ssss _iiii_dddd _****_////
               _ssss_hhhh_oooo_rrrr_tttt    _uuuu_tttt______tttt_yyyy_pppp_eeee_;;;;       _////_**** _tttt_yyyy_pppp_eeee _oooo_ffff _eeee_nnnn_tttt_rrrr_yyyy _****_////
               _ssss_tttt_rrrr_uuuu_cccc_tttt   _eeee_xxxx_iiii_tttt______ssss_tttt_aaaa_tttt_uuuu_ssss _{{{{
                   _ssss_hhhh_oooo_rrrr_tttt     _eeee______tttt_eeee_rrrr_mmmm_iiii_nnnn_aaaa_tttt_iiii_oooo_nnnn_;;;;  _////_**** _tttt_eeee_rrrr_mmmm_iiii_nnnn_aaaa_tttt_iiii_oooo_nnnn _ssss_tttt_aaaa_tttt_uuuu_ssss _****_////
                   _ssss_hhhh_oooo_rrrr_tttt     _eeee______eeee_xxxx_iiii_tttt_;;;;         _////_**** _eeee_xxxx_iiii_tttt _ssss_tttt_aaaa_tttt_uuuu_ssss _****_////
               _}}}} _uuuu_tttt______eeee_xxxx_iiii_tttt_;;;;              _////_**** _eeee_xxxx_iiii_tttt _ssss_tttt_aaaa_tttt_uuuu_ssss _oooo_ffff _aaaa _pppp_rrrr_oooo_cccc_eeee_ssss_ssss
                                       _////_**** _mmmm_aaaa_rrrr_kkkk_eeee_dddd _aaaa_ssss _DDDD_EEEE_AAAA_DDDD______PPPP_RRRR_OOOO_CCCC_EEEE_SSSS_SSSS _****_////
               _ssss_tttt_rrrr_uuuu_cccc_tttt   _tttt_iiii_mmmm_eeee_vvvv_aaaa_llll _uuuu_tttt______tttt_vvvv_;;;; _////_**** _tttt_iiii_mmmm_eeee _eeee_nnnn_tttt_rrrr_yyyy _wwww_aaaa_ssss _mmmm_aaaa_dddd_eeee _****_////
               _llll_oooo_nnnn_gggg     _uuuu_tttt______ssss_eeee_ssss_ssss_iiii_oooo_nnnn_;;;;    _////_**** _ssss_eeee_ssss_ssss_iiii_oooo_nnnn _IIII_DDDD_,,,, _uuuu_ssss_eeee_dddd _ffff_oooo_rrrr _wwww_iiii_nnnn_dddd_oooo_wwww_iiii_nnnn_gggg _****_////
               _llll_oooo_nnnn_gggg     _pppp_aaaa_dddd_[[[[_5555_]]]]_;;;;        _////_**** _rrrr_eeee_ssss_eeee_rrrr_vvvv_eeee_dddd _ffff_oooo_rrrr _ffff_uuuu_tttt_uuuu_rrrr_eeee _uuuu_ssss_eeee _****_////
               _ssss_hhhh_oooo_rrrr_tttt    _uuuu_tttt______ssss_yyyy_ssss_llll_eeee_nnnn_;;;;     _////_**** _llll_eeee_nnnn_gggg_tttt_hhhh _oooo_ffff _uuuu_tttt______hhhh_oooo_ssss_tttt _iiii_nnnn_cccc_llll_uuuu_dddd_iiii_nnnn_gggg _NNNN_UUUU_LLLL_LLLL _****_////
               _cccc_hhhh_aaaa_rrrr     _uuuu_tttt______hhhh_oooo_ssss_tttt_[[[[_2222_5555_7777_]]]]_;;;;  _////_**** _hhhh_oooo_ssss_tttt _nnnn_aaaa_mmmm_eeee_,,,, _iiii_ffff _rrrr_eeee_mmmm_oooo_tttt_eeee _****_////
          _}}}}_;;;;



                                                                        PPPPaaaaggggeeee 1111






ggggeeeettttuuuuttttxxxx((((3333CCCC))))                                                          ggggeeeettttuuuuttttxxxx((((3333CCCC))))



     _gggg_eeee_tttt_uuuu_tttt_xxxx_eeee_nnnn_tttt reads the next entry from a _uuuu_tttt_mmmm_pppp_xxxx-like file.  If the file is
     not already open, it opens it.  If it reaches the end of the file, it
     fails.

     _gggg_eeee_tttt_uuuu_tttt_xxxx_iiii_dddd searches forward from the last entry read or, if no entries have
     been read, from the first entry in the _uuuu_tttt_mmmm_pppp_xxxx file until it finds an entry
     with a _uuuu_tttt______tttt_yyyy_pppp_eeee matching _i_d->_uuuu_tttt______tttt_yyyy_pppp_eeee if the type specified is _RRRR_UUUU_NNNN______LLLL_VVVV_LLLL_,,,,
     _BBBB_OOOO_OOOO_TTTT______TTTT_IIII_MMMM_EEEE_,,,, _OOOO_LLLL_DDDD______TTTT_IIII_MMMM_EEEE, or _NNNN_EEEE_WWWW______TTTT_IIII_MMMM_EEEE_....  If the type specified in _i_d is
     _IIII_NNNN_IIII_TTTT______PPPP_RRRR_OOOO_CCCC_EEEE_SSSS_SSSS_,,,, _LLLL_OOOO_GGGG_IIII_NNNN______PPPP_RRRR_OOOO_CCCC_EEEE_SSSS_SSSS_,,,, _UUUU_SSSS_EEEE_RRRR______PPPP_RRRR_OOOO_CCCC_EEEE_SSSS_SSSS, or _DDDD_EEEE_AAAA_DDDD______PPPP_RRRR_OOOO_CCCC_EEEE_SSSS_SSSS, then _gggg_eeee_tttt_uuuu_tttt_xxxx_iiii_dddd
     will return a pointer to the first entry whose type is one of these four
     and whose _u_t__i_d field matches _i_d->_uuuu_tttt______iiii_dddd.  If the end of file is reached
     without a match, it fails.

     _gggg_eeee_tttt_uuuu_tttt_xxxx_llll_iiii_nnnn_eeee searches forward from the last entry read or, if no entries
     have been read, from the first entry in the _uuuu_tttt_mmmm_pppp_xxxx file until it finds an
     entry of the type _LLLL_OOOO_GGGG_IIII_NNNN______PPPP_RRRR_OOOO_CCCC_EEEE_SSSS_SSSS or _UUUU_SSSS_EEEE_RRRR______PPPP_RRRR_OOOO_CCCC_EEEE_SSSS_SSSS which also has a _u_t__l_i_n_e
     string matching the _l_i_n_e->_uuuu_tttt______llll_iiii_nnnn_eeee string.  If the end of file is reached
     without a match, it fails.

     _pppp_uuuu_tttt_uuuu_tttt_xxxx_llll_iiii_nnnn_eeee writes the supplied _uuuu_tttt_mmmm_pppp_xxxx structure into the _uuuu_tttt_mmmm_pppp_xxxx file.  It
     uses _gggg_eeee_tttt_uuuu_tttt_xxxx_iiii_dddd to search forward for the proper place if it finds that it
     is not already at the proper place.  It is expected that normally the
     user of _pppp_uuuu_tttt_uuuu_tttt_xxxx_llll_iiii_nnnn_eeee will have searched for the proper entry using one of
     the _gggg_eeee_tttt_uuuu_tttt_xxxx routines.  If so, _pppp_uuuu_tttt_uuuu_tttt_xxxx_llll_iiii_nnnn_eeee will not search.  If _pppp_uuuu_tttt_uuuu_tttt_xxxx_llll_iiii_nnnn_eeee
     does not find a matching slot for the new entry, it will append a new
     entry to the end of the file.  It returns a pointer to the _uuuu_tttt_mmmm_pppp_xxxx
     structure.

     _ssss_eeee_tttt_uuuu_tttt_xxxx_eeee_nnnn_tttt resets the input stream to the beginning of the file.  This
     should be done before each search for a new entry if it is desired that
     the entire file be examined.

     _eeee_nnnn_dddd_uuuu_tttt_xxxx_eeee_nnnn_tttt closes the currently open file.

     _uuuu_tttt_mmmm_pppp_xxxx_nnnn_aaaa_mmmm_eeee allows the user to change the name of the file examined, from
     _////_vvvv_aaaa_rrrr_////_aaaa_dddd_mmmm_////_uuuu_tttt_mmmm_pppp_xxxx to any other file.  It is most often expected that this
     other file will be _////_vvvv_aaaa_rrrr_////_aaaa_dddd_mmmm_////_wwww_tttt_mmmm_pppp_xxxx.  If the file does not exist, this will
     not be apparent until the first attempt to reference the file is made.
     _uuuu_tttt_mmmm_pppp_xxxx_nnnn_aaaa_mmmm_eeee does not open the file.  It just closes the old file if it is
     currently open and saves the new file name.  The new file name must end
     with the character ``_xxxx'' to allow the name of the corresponding _uuuu_tttt_mmmm_pppp file
     to be easily obtainable (otherwise an error code of 1 is returned).

     _gggg_eeee_tttt_uuuu_tttt_mmmm_pppp copies the information stored in the fields of the _uuuu_tttt_mmmm_pppp_xxxx
     structure to the corresponding fields of the _uuuu_tttt_mmmm_pppp structure. If the
     information in any field of _uuuu_tttt_mmmm_pppp_xxxx does not fit in the corresponding _uuuu_tttt_mmmm_pppp
     field, the data is truncated.

     _gggg_eeee_tttt_uuuu_tttt_mmmm_pppp_xxxx copies the information stored in the fields of the _uuuu_tttt_mmmm_pppp
     structure to the corresponding fields of the _uuuu_tttt_mmmm_pppp_xxxx structure.





                                                                        PPPPaaaaggggeeee 2222






ggggeeeettttuuuuttttxxxx((((3333CCCC))))                                                          ggggeeeettttuuuuttttxxxx((((3333CCCC))))



     _uuuu_pppp_dddd_wwww_tttt_mmmm_pppp checks the existence of _w_f_i_l_e and its parallel file, whose name
     is obtained by appending an ``_xxxx'' to _w_f_i_l_e.  If only one of them exists,
     the second one is created and initialized to reflect the state of the
     existing file. _u_t_m_p is written to _w_f_i_l_e and the corresponding _uuuu_tttt_mmmm_pppp_xxxx
     structure is written to the parallel file.

     _uuuu_pppp_dddd_wwww_tttt_mmmm_pppp_xxxx checks the existence of _w_f_i_l_e_x and its parallel file, whose name
     is obtained by truncating the final ``_xxxx'' from _w_f_i_l_e_x.  If only one of
     them exists, the second one is created and initialized to reflect the
     state of the existing file. _u_t_m_p_x is written to _w_f_i_l_e_x, and the
     corresponding _uuuu_tttt_mmmm_pppp structure is written to the parallel file.

FFFFIIIILLLLEEEESSSS
     _////_vvvv_aaaa_rrrr_////_aaaa_dddd_mmmm_////_uuuu_tttt_mmmm_pppp, _////_vvvv_aaaa_rrrr_////_aaaa_dddd_mmmm_////_uuuu_tttt_mmmm_pppp_xxxx
     _////_vvvv_aaaa_rrrr_////_aaaa_dddd_mmmm_////_wwww_tttt_mmmm_pppp, _////_vvvv_aaaa_rrrr_////_aaaa_dddd_mmmm_////_wwww_tttt_mmmm_pppp_xxxx

SSSSEEEEEEEE AAAALLLLSSSSOOOO
     _tttt_tttt_yyyy_ssss_llll_oooo_tttt(3C), _gggg_eeee_tttt_uuuu_tttt(3C), _uuuu_tttt_mmmm_pppp(4), _uuuu_tttt_mmmm_pppp_xxxx(4).

DDDDIIIIAAAAGGGGNNNNOOOOSSSSTTTTIIIICCCCSSSS
     A null pointer is returned upon failure to read, whether for permissions
     or having reached the end of file, or upon failure to write.

WWWWAAAARRRRNNNNIIIINNNNGGGG
     All changes to _////_vvvv_aaaa_rrrr_////_aaaa_dddd_mmmm_////_wwww_tttt_mmmm_pppp must also be logged in _////_vvvv_aaaa_rrrr_////_aaaa_dddd_mmmm_////_wwww_tttt_mmmm_pppp_xxxx.  Most
     commands that extract information from these files silently discard all
     _wwww_tttt_mmmm_pppp_xxxx entries without corresponding _wwww_tttt_mmmm_pppp entries.

NNNNOOOOTTTTEEEESSSS
     The most current entry is saved in a static structure.  Multiple accesses
     require that it be copied before further accesses are made.  On each call
     to either _gggg_eeee_tttt_uuuu_tttt_xxxx_iiii_dddd or _gggg_eeee_tttt_uuuu_tttt_xxxx_llll_iiii_nnnn_eeee, the routine examines the static
     structure before performing more I/O.  If the contents of the static
     structure match what it is searching for, it looks no further.  For this
     reason, to use _gggg_eeee_tttt_uuuu_tttt_xxxx_llll_iiii_nnnn_eeee to search for multiple occurrences it would be
     necessary to zero out the static after each success, or _gggg_eeee_tttt_uuuu_tttt_xxxx_llll_iiii_nnnn_eeee would
     just return the same structure over and over again.  There is one
     exception to the rule about emptying the structure before further reads
     are done.  The implicit read done by _pppp_uuuu_tttt_uuuu_tttt_xxxx_llll_iiii_nnnn_eeee (if it finds that it is
     not already at the correct place in the file) will not alter the contents
     of the static structure returned by the _gggg_eeee_tttt_uuuu_tttt_xxxx_eeee_nnnn_tttt, _gggg_eeee_tttt_uuuu_tttt_xxxx_iiii_dddd, or
     _gggg_eeee_tttt_uuuu_tttt_xxxx_llll_iiii_nnnn_eeee routines, if the user has just modified those contents and
     passed the pointer back to _pppp_uuuu_tttt_uuuu_tttt_xxxx_llll_iiii_nnnn_eeee.

     _gggg_eeee_tttt_uuuu_tttt_xxxx_eeee_nnnn_tttt, _gggg_eeee_tttt_uuuu_tttt_xxxx_iiii_dddd, _gggg_eeee_tttt_uuuu_tttt_xxxx_llll_iiii_nnnn_eeee, and _pppp_uuuu_tttt_uuuu_tttt_xxxx_llll_iiii_nnnn_eeee, place file locks on the
     used during function execution. File locks are not held across calls to
     these or other functions, but signals may interrupt the execution of
     these functions allowing file locks to be held. When using these
     functions where a signal may interrupt function execution, _eeee_nnnn_dddd_uuuu_tttt_xxxx_eeee_nnnn_tttt
     should be called by signal handlers to release any file locks acquired by
     an interrupted function.




                                                                        PPPPaaaaggggeeee 3333






ggggeeeettttuuuuttttxxxx((((3333CCCC))))                                                          ggggeeeettttuuuuttttxxxx((((3333CCCC))))























































                                                                        PPPPaaaaggggeeee 4444